@emotion/sheet

What is @emotion/sheet?

The @emotion/sheet package is part of the Emotion library, which is a popular CSS-in-JS library that allows developers to write CSS styles with JavaScript. The @emotion/sheet package provides a low-level utility for managing style sheets. It is used internally by Emotion to insert styles into the DOM, but it can also be used directly for more control over how styles are inserted.

What are @emotion/sheet's main functionalities?

Creating and inserting a style sheet

This feature allows you to create a new style sheet and insert CSS rules into it. The 'speedy' option enables faster insertion of rules by using CSSOM APIs.

{"import { StyleSheet } from '@emotion/sheet';\nconst sheet = new StyleSheet({ speedy: true });\nsheet.insert('.css-12345 { color: hotpink; }');"}

Flushing styles

This feature allows you to remove all rules from the style sheet. This can be useful for cleaning up styles in server-side rendering or during hot module replacement in development.

{"import { StyleSheet } from '@emotion/sheet';\nconst sheet = new StyleSheet({ speedy: true });\nsheet.insert('.css-12345 { color: hotpink; }');\nsheet.flush();"}

Other packages similar to @emotion/sheet

jss

JSS is an authoring tool for CSS which allows you to use JavaScript to describe styles in a declarative, conflict-free and reusable way. It is similar to @emotion/sheet in that it provides a JavaScript API to manage style sheets, but it also includes a more extensive API for defining and composing styles.

aphrodite

Aphrodite is another CSS-in-JS library that allows you to write styles in JavaScript and attach them to your components. It differs from @emotion/sheet by providing a higher-level API and automatic handling of vendor prefixing, fallbacks, and keyframes, whereas @emotion/sheet is a lower-level utility for style sheet management.

styled-components

Styled-components is a library for styling React components using tagged template literals. It provides a similar experience to writing CSS in JS but focuses more on component-level styles. Unlike @emotion/sheet, which is a utility for managing style sheets, styled-components abstracts the style sheet management and provides a more developer-friendly API for styling components.

glamor

Glamor is a CSS-in-JS library that allows for styling components with JavaScript. It is similar to @emotion/sheet in that it provides an API for inserting and managing styles, but it also includes features like pseudo-class support and media queries, which are not the primary focus of @emotion/sheet.

README

@emotion/sheet

A StyleSheet for css-in-js libraries

yarn add @emotion/sheet

import { StyleSheet } from '@emotion/sheet'

const sheet = new StyleSheet({ key: '', container: document.head })

sheet.insert('html { color: hotpink; }')

Note: This is not useful for server-side rendering, you should implement SSR seperately

StyleSheet

Options

type Options = {
  nonce?: string
  key: string
  container: Node
  speedy?: boolean
  prepend?: boolean
}

nonce

A nonce that will be set on each style tag that the sheet inserts for Content Security Policies.

container

A DOM Node that the sheet will insert all of it's style tags into, this is useful for inserting styles into iframes.

key

This will be set as the value of the data-emotion attribute on the style tags that get inserted. This is useful to identify different sheets.

speedy

This defines how rules are inserted. If it is true, rules will be inserted with insertRule which is very fast but doesn't allow rules to be edited in DevTools. If it is false, rules will be inserted by appending text nodes to style elements which is much slower than insertRule but allows rules to be edited in DevTools. By default, speedy is enabled in production and disabled in development.

prepend

Deprecated: Please use insertionPoint option instead.

This defines where rules are inserted into the container. By default they are appended but this can be changed by using prepend: true option.

insertionPoint

This defines specific dom node after which the rules are inserted into the container. You can use a meta tag to specify the specific location:

const head = document.querySelector('head')

// <meta name="emotion-insertion-point" content="">
const emotionInsertionPoint = document.createElement('meta')
emotionInsertionPoint.setAttribute('name', 'emotion-insertion-point')
emotionInsertionPoint.setAttribute('content', '')

head.appendChild(emotionInsertionPoint)

// the emotion sheets should be inserted right after the meta tag
const cache = createCache({
  key: 'my-app',
  insertionPoint: emotionInsertionPoint
})

function App() {
  return (
    <CacheProvider value={cache}>
      <Main />
    </CacheProvider>
  )
}

Methods

insert

This method inserts a single rule into the document. It must be a single rule otherwise an error will be thrown in speedy mode which is enabled by default in production.

flush

This method will remove all style tags that were inserted into the document.

hydrate

This method moves given style elements into sheet's container and put them into internal tags collection. It's can be used for SSRed styles.

Example with all options

import { StyleSheet } from '@emotion/sheet'

const container = document.createElement('div')

document.head.appendChild(container)

const sheet = new StyleSheet({
  nonce: 'some-nonce',
  key: 'some-key',
  container
})

sheet.insert('html { color: hotpink; }')

sheet.flush()

Thanks

This StyleSheet is based on glamor's StyleSheet written by Sunil Pai. ❤️